IRIX Base Documentation 2001 May

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / a_man / cat1 / gendist.z / gendist

Wrap

Text File | 2001-04-17 | 30.7 KB | 661 lines

ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) NNNNAAAAMMMMEEEE gendist - generate a software distribution SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ggggeeeennnnddddiiiisssstttt [[[[ ----rrrrbbbbaaaasssseeee _r_b_a_s_e ] [ ----rrrrooooooootttt _r_b_a_s_e ] [ ----ssssbbbbaaaasssseeee _s_b_a_s_e ] [ ----ssssoooouuuurrrrcccceeee _s_b_a_s_e ] [ ----iiiiddddbbbb _i_d_b_f_i_l_e ] [ ----ssssppppeeeecccc _s_p_e_c_f_i_l_e ] [ ----ddddiiiisssstttt _d_i_s_t_d_i_r ] [ ----mmmmrrrr _f_i_l_e ] [ ----ssssaaaa _f_i_l_e ] [ ----ccccrrrreeeeaaaattttoooorrrr _n_a_m_e ] [ ----vvvveeeerrrrbbbboooosssseeee ] [ ----mmmmaaaaiiiinnnntttt ] [ ----nnnnooooccccoooommmmpppprrrreeeessssssss ] [ ----nnnnoooossssttttrrrriiiipppp ] [ ----ggggeeeennnniiiiddddbbbb ] [ ----ggggeeeennnnssssppppeeeecccc ] [ ----aaaallllllll ] [ ----iiiiggggnnnnoooorrrreeeeeeeemmmmppppttttyyyy ] [ _p_a_t_t_e_r_n_s ... ] DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN _G_e_n_d_i_s_t generates the primary components for software products. These are the product descriptor, the product idb, and the images. The required input is a tree containing all of the files to be shipped, a master idb containing a description of each file or directory to be included in the product, and a distribution specification (spec) file that describes the product structure. _G_e_n_d_i_s_t reads the distribution specification file and generates products as defined in that file. For each product, the product descriptor file is created with the name _p_r_o_d (for example), then the product idb is generated with the name _p_r_o_d....iiiiddddbbbb, and then the images with the name _p_r_o_d....iiiimmmmaaaaggggeeee for each _i_m_a_g_e defined in the distribution specification file. Normally, all components of all products defined in the _s_p_e_c_f_i_l_e are generated. The optional _p_a_t_t_e_r_n_s at the end of the command line are shell-style patterns that identify particular files to be generated. Note that these patterns are matched against the name to be created, not against existing files on the disk. Such patterns should be protected from the shell expansion mechanisms. For example, to generate all of the components of the _f_t_n product, use: gendist ... "ftn*" Files are created in the _d_i_s_t_d_i_r, which is ``$rbase/usr/dist'' by default. Options: ----rrrrbbbbaaaasssseeee _r_b_a_s_e ----rrrrooooooootttt _r_b_a_s_e Set the ``root base,'' which is the pathname of the top of the destination tree. The default _r_b_a_s_e is /root, overridden by the environment variable rbase. ----ssssbbbbaaaasssseeee _s_b_a_s_e ----ssssoooouuuurrrrcccceeee _s_b_a_s_e Set the ``source base,'' which is the pathname of the top of the source (or build) tree. The default _s_b_a_s_e is /usr/src, PPPPaaaaggggeeee 1111 ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) overridden by the environment variable sbase. ----iiiiddddbbbb _i_d_b_f_i_l_e Set the pathname of the idb. The default is $rbase/etc/idb, overridden by the environment variable idb. The idbfile must be sorted on the 5th and 6th fields. ----ssssppppeeeecccc _s_p_e_c_f_i_l_e Set the pathname of the spec file. The default is $rbase/etc/spec. ----ddddiiiisssstttt _d_i_s_t_d_i_r Create the product components in _d_i_s_t_d_i_r. The default is $rbase/usr/dist, overridden by the environment variable dist. ----ssssaaaa _s_a_f_i_l_e Set the pathname of _s_a_f_i_l_e. The default is sa. ----mmmmrrrr _m_r_f_i_l_e Set the pathname of the _m_r_f_i_l_e. The default is mr. ----ccccrrrreeeeaaaattttoooorrrr _n_a_m_e Set the "created by" field in the product to _n_a_m_e. ----vvvveeeerrrrbbbboooosssseeee Work verbosely, with more output as the distribution is created. ----nnnnooooccccoooommmmpppprrrreeeessssssss Do not compress the images being built. ----nnnnoooossssttttrrrriiiipppp Do not strip any of the executables. ----mmmmaaaaiiiinnnntttt Generate maintenance product. ----ggggeeeennnniiiiddddbbbb Generate an idb from the rbase tree to $rbase/etc/idb. ----ggggeeeennnnssssppppeeeecccc Generate a simple spec file to $rbase/etc/spec. ----aaaallllllll Generate the product distribution as well as the spec file and the idb file. ----iiiiggggnnnnoooorrrreeeeeeeemmmmppppttttyyyy Do not add empty subsystems to the image and do not emit a warning message. There is a predefined sequence for building and installing software releases, one part of which is to use _g_e_n_d_i_s_t to generate the software images. Before and after using _g_e_n_d_i_s_t, there are other commands to use. The simplified sequence of events is: PPPPaaaaggggeeee 2222 ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) 1. Build the software with ``make install'' and the environment variable RAWIDB set. 2. Sort the idb file with ``sort +4u -6 <$RAWIDB >idb''. 3. Use _g_e_n_d_i_s_t on idb file (created in step 2) and spec file; output includes images. 4. Use _d_i_s_t_c_p to copy images to other places. 5. Use _i_n_s_t to install the images. DDDDIIIISSSSTTTTRRRRIIIIBBBBUUUUTTTTIIIIOOOONNNN SSSSPPPPEEEECCCCIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN The distribution spec file is a text description of the product, image and subsystem hierarchy, in the following form: include file define variable value product pp attribute ... image ii attribute ... subsystem ss attribute ... endsubsys endimage endproduct Products may contain multiple images. Images may contain multiple subsystems. Attributes apply to the nearest enclosing product, image or subsystem (see descriptions below). When specifying an attribute's value(s), use double-quotes to protect whitespace, and single-quotes to prevent expansion of ${variables}. In the attribute descriptions that follow, a ssssuuuubbbbssssyyyysssstttteeeemmmm----rrrraaaannnnggggeeee is a three- part product.image.subsystem identifier, followed by a low version number and a high version number, all separated by whitespace. Except within a rrrreeeeppppllllaaaacccceeeessss statement (see below) the keyword mmmmaaaaxxxxiiiinnnntttt may be used to indicate the highest possible version number. For example: x.y.z 1000 2000 x.y.z 1 maxint x.books.eoe 2000 2000 The following attributes may be used. iiiidddd """"_i_d-_s_t_r_i_n_g"""" A one-line description or title of the enclosing product, image, or subsystem. vvvveeeerrrrssssiiiioooonnnn _v_e_r_s_i_o_n-_n_u_m_b_e_r A version number should be specified at the image level. All subsystems in that image inherit this version number. Version numbers normally increase with each new release of the product, so that inst can properly identify upgrade subsystems. PPPPaaaaggggeeee 3333 ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) eeeexxxxpppp _e_x_p_r_e_s_s_i_o_n This attribute is placed at the subsystem level, and specifies which files belong to that subsystem. All files in the idb having one or more group-tags that match _e_x_p_r_e_s_s_i_o_n are included in that subsystem when the distribution is created. The group-tags in the idb are identifiers that categorize the files is some convenient way (MAN or DSO for example). The _e_x_p_r_e_s_s_i_o_n is a boolean function written using these tags, and the C logical operators ||, &&, ! and (). For example: exp MAN exp EOE exp "!noship && (EOE || BITMAPS || DSO)" oooorrrrddddeeeerrrr _o_r_d_e_r-_n_u_m_b_e_r This attribute is placed at image level to control the order of installations. Images with lower order numbers are installed before images with higher order numbers. ddddeeeeffffaaaauuuulllltttt ddddeeeeffffaaaauuuulllltttt ((((_e_x_p_r_e_s_s_i_o_n)))) The subsystem is marked for default installation by inst. If a parenthesized _e_x_p_r_e_s_s_i_o_n is given, the subsystem is default only on hardware platforms matching that expression. See HARDWARE EXPRESSIONS. rrrreeeeqqqquuuuiiiirrrreeeedddd rrrreeeeqqqquuuuiiiirrrreeeedddd ((((_e_x_p_r_e_s_s_i_o_n)))) The subsystem is required for installation by inst. Removal of the subsystem is disallowed (upgrade is permitted). Only subsystems containing critical operating system functions should be marked as required. If a parenthesized _e_x_p_r_e_s_s_i_o_n is given, the subsystem is default only on hardware platforms matching that expression. See HARDWARE EXPRESSIONS. mmmmiiiinnnniiiirrrrooooooootttt mmmmiiiinnnniiiirrrrooooooootttt ((((_e_x_p_r_e_s_s_i_o_n)))) A miniroot installation is recommended (not required) or a reboot is required to complete the installation. If a parenthesized _e_x_p_r_e_s_s_i_o_n is given, the subsystem is miniroot only on hardware platforms matching that expression. See HARDWARE EXPRESSIONS. aaaauuuuttttoooommmmiiiinnnniiiirrrrooooooootttt ((((_s_u_b_s_y_s_t_e_m-_r_a_n_g_e)))) A miniroot installation is required if any subsystem in the specified _s_u_b_s_y_s_t_e_m-_r_a_n_g_e is currently installed. This keyword should be used whenever a "live" installation (in multi-user mode) causes failures in or harmfully affects other user processes that may be executing during the inst session. mmmmaaaacccchhhh """"_e_x_p_r_e_s_s_i_o_n"""" Specify that the enclosing product, image or subsystem is suitable for installation only on certain hardware platforms matching the PPPPaaaaggggeeee 4444 ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) _e_x_p_r_e_s_s_i_o_n. Multiple mach expressions for a single product, image or subsystem are OR'd. See HARDWARE EXPRESSIONS. pppprrrreeeerrrreeeeqqqq ((((_s_u_b_s_y_s_t_e_m-_r_a_n_g_e ...)))) Installation of the subsystem also requires installation of the prerequisite subsystems specified in the ranges. If a subsystem has multiple prereq rules, inst permits its installation if any one of those rules is satisfied. In the following example, subsystem s can be installed if either: both p.q.r (any version between 100-200, inclusive) and x.y.z (any version greater than 400) are also installed; or, a.b.c version 1000 is also installed: subsystem s prereq ( p.q.r 100 200 x.y.z 400 maxint) prereq ( a.b.c 1000 1000 ) endsubsys rrrreeeeppppllllaaaacccceeeessss _s_u_b_s_y_s_t_e_m-_r_a_n_g_e oooobbbbssssoooolllleeeetttteeeessss _s_u_b_s_y_s Installation of the subsystem automatically causes the removal of subsystems specified by the _r_a_n_g_e. A subsystem may have multiple replaces rules. It is not necessary to supply a replacement rule for other versions of subsystems by the same name (this is enforced automatically be inst). Wildcards (*) are permitted in the subsystem identifier in _s_u_b_s_y_s_t_e_m-_r_a_n_g_e. If the mmmmaaaaxxxxiiiinnnntttt keyword is used as the high version number, it will automatically be converted to one less than the version number of the containing subsystem. The shorthand oooobbbbssssoooolllleeeetttteeeessss xxxx....yyyy....zzzz is interpreted as rrrreeeeppppllllaaaacccceeeessss xxxx....yyyy....zzzz 0000 mmmmaaaaxxxxiiiinnnntttt. The following rules are equivalent: image i version N subsystem s replaces x.y.z 0 N-1 replaces x.y.z 0 maxint obsoletes x.y.z endsubsys endimage During installation, a subsystem is labeled upgrade (downgrade) if it replaces any other currently installed subsystem with a lesser (greater) version number, even if the two subsystems have different names. Whenever a subsystem is upgraded or downgraded, its patches are also removed. For this reason, a subsystem X need not declare replacement rules for patches that follow subsystems replaced by X. PPPPaaaaggggeeee 5555 ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) iiiinnnnccccoooommmmppppaaaatttt _s_u_b_s_y_s_t_e_m-_r_a_n_g_e The subsystem is incompatible with the subsystem specified in the _s_u_b_s_y_s_t_e_m-_r_a_n_g_e. This rule should be used when two subsystems cannot coexist on the same system. A conflict will result if the user attempts any installation that will result in both subsystems being installed on the system. uuuuppppddddaaaatttteeeessss _s_u_b_s_y_s_t_e_m-_r_a_n_g_e The subsystem automatically satisfies all prerequisite rules for any subsystem X which has a prereq rule for subsystems specified in the _s_u_b_s_y_s_t_e_m-_r_a_n_g_e. This is useful for honoring the prerequisite rules of previously released (hence unchangeable) products, when the subsystem name is changed in the newer version. The uuuuppppddddaaaatttteeeessss rule does not imply rrrreeeeppppllllaaaacccceeeessss. ppppaaaattttcccchhhh Declare the subsystem to be a patch that replaces files in another subsystem. A patch can also introduce new files. When a patch is installed, any previously installed versions of its files are achived under $rbase/var/inst/patchbase. When a patch is removed, the original files are restored. A patch subsystem must have a ffffoooolllllllloooowwwwssss rule. A patch may replace other patches, but may not replace other non-patch subsystems. ffffoooolllllllloooowwwwssss _s_u_b_s_y_s_t_e_m-_r_a_n_g_e Specify that a patch subsystem can only be installed if the base subsystem (specified by _s_u_b_s_y_s_t_e_m-_r_a_n_g_e) is also installed. A patch may have multiple follows rules, provided that they all reference the same base subsystem. This allows disjoint version ranges to be specified. A follows rule can only be used within a ppppaaaattttcccchhhh subsystem. ccccuuuuttttppppooooiiiinnnntttt _d_i_r_e_c_t_o_r_y This attribute may only be used at the outermost product level (not at the image or subsystem level). It declares _d_i_r_e_c_t_o_r_y to be a cutpoint that is owned by the enclosing product, and that it is safe for inst to move the entire directory to an alternate drive when disk space on the system drive is limited. When choosing cutpoints, identify the highest-level directories that contain only files or sub-directories owned by your product. Directories that consume large amounts of disk space are good candidates. Multiple cutpoints are permitted. For example product gizmo cutpoint /usr/Gizmo ... endproduct could be used if all files under /usr/Gizmo are owned by the gizmo product. The inst command PPPPaaaaggggeeee 6666 ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) Inst> admin relocate gizmo /disk3 will move the contents of /usr/Gizmo to /disk3/usr/Gizmo, and then replace /usr/Gizmo with a symbolic link to ../disk3/usr/Gizmo. It is desirable, but not required, for a product to install all of its files underneath cutpoints. This property simplifies the task of sharing software in a network environment using NFS mounts. For example if gizmo installs /usr/lib/X11/app-defaults/Gizmo then that file will not be moved when /usr/Gizmo is relocated. Before declaring a cutpoint directory, it is advisable to check for self-containment. Problems may arise with relative symbolic links which follow a path up through the cutpoint itself, as in: /usr/Gizmo/bin/ls -> ../../../bin/ls If the directory /usr/Gizmo is moved to a new location at a different depth, such as /disk3/usr/Gizmo, then the path /usr/Gizmo/bin/ls might no longer be valid. IIIIDDDDBBBB FFFFIIIILLLLEEEE The idb contains one line for each file or directory in an entire product. The following optional attributes can be specified. ccccoooonnnnffffiiiigggg(((([update|suggest|noupdate])))) Inst gives special treatment to configuration files if a version already exists on disk and and either: the file has been altered since it was last installed (modified); or the file is not present in the installation history (foreign). During removals, inst does not remove modified config files. During installations, config files are installed normally, except when a modified or foreign version already exists on disk. In that case the following variations occur: ccccoooonnnnffffiiiigggg(_u_p_d_a_t_e) before the file is installed, the modified/foreign version is saved as file.O. ccccoooonnnnffffiiiigggg(_s_u_g_g_e_s_t) the file is installed under the name file.N. The modified/foreign version remains unchanged. ccccoooonnnnffffiiiigggg(_n_o_u_p_d_a_t_e) no new version of the file is installed. The modified/foreign version remains unchanged. nnnnoooohhhhiiiisssstttt After the file is installed, no record of it is kept in the installation history. Useful for scripts which delete themselves PPPPaaaaggggeeee 7777 ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) (for example during a postop), so that showfiles -B does not report them as missing. ddddeeeellllhhhhiiiisssstttt The file is completely ignored by inst. Provided only for backwards compatibility. ddddeeeevvvv((((_m_a_j _m_i_n)))) Specify the major and minor device numbers. This attribute is required if the file is a block or character special device. ssssyyyymmmmvvvvaaaallll((((_v_a_l_u_e)))) Specifies the link value. Required when the file is a symbolic link. mmmmaaaacccchhhh(_e_x_p_r) Install the file only on hardware platforms matching _e_x_p_r (see HARDWARE EXPRESSIONS below). eeeexxxxiiiittttoooopppp(_c_m_d) If the file is installed, execute _c_m_d in a bourne shell, at the end of the installation. Inst sets the following variables in the environment for exitops, preops, postops and removeops: rrrrbbbbaaaasssseeee is set to the root installation directory (see the -r option of inst). Exitops typically conduct all their activity relative to $rbase. ddddiiiisssstttt is set to the location of the software distribution. iiiinnnnssssttttmmmmooooddddeeee is set to _n_o_r_m_a_l for miniroot installs into /root and live installs into /, or _c_l_i_e_n_t for diskless client-tree installations using client_inst(1M), or _p_r_o_t_o_t_y_p_e during all other installations. ddddiiiisssskkkklllleeeessssssss is set to _c_l_i_e_n_t during diskless installations using client_inst(1M), or _s_h_a_r_e during diskless installations using share_inst(1M), or _n_o_n_e for other, non-diskless installations. mmmmrrrr is set to _t_r_u_e during miniroot installations, set to _f_a_l_s_e otherwise. pppprrrreeeeoooopppp(_c_m_d) Like an exitop, except that Execute _c_m_d just before the file is installed. ppppoooossssttttoooopppp(_c_m_d) Execute _c_m_d just after the file is installed. rrrreeeemmmmoooovvvveeeeoooopppp(_c_m_d) Execute _c_m_d if its subsystem is removed. Removeops are executed at the end of an install/remove run, along with any exitops. Removeops are only executed after strict subsystem removals, and not during an PPPPaaaaggggeeee 8888 ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) upgrade. During an upgrade, any cleanup tasks should be performed in the exitop of the upgrade product. sssshhhhaaaaddddoooowwww Causes the file to be installed as file.shd during "live" installations when rbase is /. When the system is shutdown, file.shd is renamed to file and only then are its exitops, preops and postops executed. During other installations (for example in the miniroot) no special actions are taken. nnnnoooossssttttrrrriiiipppp Do not invoke strip(1M) on the file, so that its symbol table is preserved. ssssttttrrrriiiippppddddssssoooo Invoke strip(1M) on the file using the -f (force) option. Useful for dynamic shared objects. See the strip(1M) manual page. nnnnoooorrrrqqqqssss Suppress requickstarting for the file after it is installed. ttttaaaagggg(_v_a_l_u_e) At build time, invoke tag(1) with an argument of _v_a_l_u_e on the file. value may be a decimal or hex number. The tag idb keyword is not copied to the final idb file since it is of no use at install time. HHHHAAAARRRRDDDDWWWWAAAARRRREEEE EEEEXXXXPPPPRRRREEEESSSSSSSSIIIIOOOONNNNSSSS Hardware expressions, or machtags, are boolean expressions evaluated at installation time against the current architecture and IRIX version number of the system on which the installation occurs, or against the machtag values given on the command line when inst -m is used. Hardware expressions are used in the spec file to restrict installation of a subsystem, image or entire product, to specific hardware platforms or IRIX releases, and to mark subsystems as default, miniroot, or required only for specific platforms. Hardware expressions in the idb file make it possible to install different versions of the same file (including no version at all), depending on the target platform. Each version of the file appears on its own idb line. At most one version of a file can be installed in a single subsystem. When multiple versions of a file are specified, inst installs the one whose machtag matches the target platform. If no matching machtag is found, inst installs the version that has no machtag (if specified). There are two distinct syntaxes for hardware expressions. The two syntaxes may not be intermixed. In both forms the construct attr=value may not be reversed, for example IP22=CPUBOARD does not work. If the leading attr= is omitted, attr is assumed to be CPUBOARD. PPPPaaaaggggeeee 9999 ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) ggggeeeennnnddddiiiisssstttt((((1111MMMM)))) The valid attributes are CPUBOARD, CPUARCH, GFXBOARD, SUBGR, VIDEO, MODE, TARGOS and DISTOS. During an inst session the variable TARGOS refers to the currently installed IRIX release, as displayed by the command "showprods -n eoe*.sw.unix". DISTOS is the version of eoe*.sw.unix on the current software distribution. These variables will have the value -1 if eoe*sw.unix is not present. FFFFiiiirrrrsssstttt ffffoooorrrrmmmm The first form is a whitespace-separated list of attribute/value expressions written as: attr=value attr=value ... An expression evalues to true if there is at least one match for every unique attribute referenced in the expression. For example "CPUBOARD=IP22 GFXBOARD=EXPRESS GFXBOARD=NEWPRESS" evalutes to true if the cpu is IP22 and the graphics board is either EXPRESS or NEWPRESS. SSSSeeeeccccoooonnnndddd ffffoooorrrrmmmm The second form is a C-like syntax in which attr=value pairs can be combined with the logical operators &&, ||, and !. The relational operators <, <=, !=, >, > may be used instead of =. Grouping with parentheses is permitted. Note: whitespace does not imply logical AND as it does in the first form. If any of the operators except = are used, then the entire expression must be written in the second form. The first-form example above could be rewritten as "CPUBOARD=IP22 && GFXBOARD=EXPRESS || GFXBOARD=NEWPRESS". SSSSEEEEEEEE AAAALLLLSSSSOOOO distcp(1M), inst(1M), install(1), showprods(1M), swpkg(1M), versions(1M). _S_o_f_t_w_a_r_e _P_a_c_k_a_g_e_r _U_s_e_r'_s _G_u_i_d_e. PPPPaaaaggggeeee 11110000